ATSUSetFontFallbacks

OSStatus ATSUSetFontFallbacks (
                     ItemCount iFontFallbacksCount,
                     ATSUFontID iFontIDs[],
                     ATSUFontFallbackMethod iFontFallbackMethod);

iFontFallbacksCount

The number of fonts that you want searched when fallback mapping is required. This should be equivalent to the number of elements in the iFontIDs array.

iFontIDs

An array of values of type ATSUFontID. Each element in the array should represent an ATSUI-compatible font, and the order of these elements should reflect the order that you want ATSUI to sequentially search them when fallback mapping is needed.

iFontFallbackMethod

A value of type ATSUFontFallbackMethod. Pass the order that you want fonts in the iFontIDs array to be searched. See Font Fallback Constants for a description of possible values.

function result

A result code. The result code kATSUInvalidFontErr indicates that the font does not correspond to any installed font. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUSetFontFallbacks function indicates the fonts to search and the search order to use when a font does not have all the glyphs for the characters it is trying to draw. If you do not call ATSUSetFontFallbacks, all valid fonts on the user's system will be searched sequentially when a substitute font is needed, and the first match will be used. You can specify this default search behavior by passing kATSUDefaultFontFallbacks in the iFontFallbackMethod parameter. This is equivalent to calling the function ATSUMatchFontsToText. ATSUSetFontFallbacks will use the first valid font it finds in the font list you specify.

If you call ATSUSetFontFallbacks and carefully order your chosen font fallbacks, the amount of time needed by ATSUI to find a suitable fallback for specific text can be significantly reduced.

VERSION NOTES

Available beginning with ATSUI 1.1.